Unique Items Shape Attribute (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / About Picture Shapes

Unique Items Shape Attribute
One of the shape attributes provided by QuickDraw GX is the unique items attribute. This attribute affects the way shapes are added to a picture:

If a picture shape does not have the unique items attribute set, QuickDraw GX adds shapes to the picture by reference.
If a picture shape does have the unique items attribute set, QuickDraw GX adds shapes to the picture by copying the shapes and adding a reference to the copy.

Although you may clear the unique items attribute for a picture at any time, you may set the unique items attribute only when a picture is empty--that is, only when the picture contains no items.
You set or clear the unique items attribute using the GXGetShapeAttributes function, which is described in the chapter "Shape Objects" of Inside Macintosh: QuickDraw GX Objects.
Figure 6-10 depicts an empty picture shape and a polygon shape. The following two figures use these shapes to illustrate the effect of the unique items attribute.
Figure 6-10 An empty picture shape and a polygon shape

Figure 6-11 shows the result of adding the polygon shape to the empty picture shape. In the left half of this figure, the picture shape does not have the unique items attribute set. In this case, adding the polygon shape to the empty picture simply adds a reference to the polygon shape to the geometry of the picture shape and increases the owner count of the polygon shape.
In the right half of this figure, the picture shape has the unique items attribute set. In this case, adding the polygon shape to the empty picture creates a deep copy of the polygon shape--including all objects referenced by the polygon shape--and adds the copy to the geometry of the picture shape. The original polygon shape is unchanged.
Figure 6-11 Adding a polygon shape to a picture shape

Figure 6-12 shows the result of adding the same polygon shape to the empty picture shape twice.
In the left half of this figure, the picture shape does not have the unique items attribute set. In this case, the first time the polygon shape is added to the empty picture, a reference to the polygon shape is added to the geometry of the picture shape and the owner count of the polygon shape is incremented. The second time the polygon is added to the picture, another reference to the polygon is added to the picture geometry and the owner count of the polygon is incremented again.
In the right half of this figure, the picture shape has the unique items attribute set. In this case, the first time the polygon shape is added to the empty picture, QuickDraw GX creates a deep copy of the polygon shape--including all objects referenced by the polygon shape--and adds a reference to the copy to the geometry of the picture shape. The original polygon shape is unchanged. The second time the polygon is added to the picture, QuickDraw GX notices that the polygon has already been added to the picture and has not been changed. Therefore, to avoid making a second deep, QuickDraw GX simply adds to the picture geometry another reference to the first deep copy.
Figure 6-12 Adding a shape to a picture twice

For more examples involving the unique items attribute, see "Adding Items With the Unique Items Attribute Set" beginning on page 6-43.